2. EL 7
  3. man-pages-es
  4. getaddrinfo(3)

Scroll to navigation

getaddrinfo(3) Manual del Programador de Linux getaddrinfo(3)

NOMBRE

getaddrinfo - traducción de servicios y direcciones de red

SINOPSIS

#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>

int getaddrinfo(const char *node, const char *service,
                const struct addrinfo *hints,
                struct addrinfo **res);

void freeaddrinfo(struct addrinfo *res);

const char *gai_strerror(int errcode);

DESCRIPCIÓN

La función getaddrinfo(3) combina la funcionalidad provista por las funciones getipnodebyname(3), getipnodebyaddr(3), getservbyname(3), y getservbyport(3) en una única interfaz. La función hilo-seguro getaddrinfo(3) crea una o más estructuras de dirección de socket que pueden ser utilizadas por las llamadas al sistema bind(2) y connect(2) para crear un socket cliente o servidor.

La función getaddrinfo(3) no se limita a la creación de estructuras de dirección de socket IPv4; puede crear estructuras de dirección de socket IPv6 si el soporte para IPv6 está disponible. Estas estructuras de dirección de socket pueden ser usadas directamente por bind(2) o connect(2), para preparar un socket cliente o servidor.

La estructura addrinfo usada por esta función contiene los siguientes miembros:

struct addrinfo {
    int     ai_flags;
    int     ai_family;
    int     ai_socktype;
    int     ai_protocol;
    size_t  ai_addrlen;
    struct sockaddr *ai_addr;
    char   *ai_canonname;
    struct addrinfo *ai_next;
};

getaddrinfo(3) modifica res para que apunte a la lista dinámica enlazada de estructuras addrinfo , enlazada por el miembro ai_next. Hay muchas razones por las que la lista enlazada puede tener más de una estructura addrinfo , incluyendo: si el host tiene más de una dirección IP; o si el mismo servicio está disponible desde múltiples protocolos de socket (uno desde una dirección SOCK_STREAM y otro desde una dirección SOCK_DGRAM , por ejemplo).

Los miembros ai_family, ai_socktype, y ai_protocol tienen el mismo significado que los correspondientes parámetros de la llamada socket(2). La función getaddrinfo(3) devuelve direcciones de socket en la familia de direcciones IPv4 o IPv6, (ai_family contendrá PF_INET o PF_INET6).

El parámetro hints especifica el tipo de socket o protocolo preferido. Un valor de NULL en hints especifica que cualquier dirección de red o protocolo es aceptable. Si este parámetro es distinto de NULL apunta a una estructura addrinfo cuyos miembros ai_family, ai_socktype, y ai_protocol especifican el tipo de socket preferido. PF_UNSPEC en ai_family especifica cualquier familia de protocolos (bien IPv4 o IPv6, por ejemplo). Un valor de 0 en ai_socktype o ai_protocol especifica que cualquier tipo de socket o protocolo es aceptable también. El miembro ai_flags especifica opciones adicionales, definidas más abajo. Se pueden especificar múltiples opciones mediante un OR lógica de todas ellas. Todos los demás miembros en el parámetro hints deben contener o bien 0, un puntero null.

El parámetro node o service , pero no ambos, pueden ser NULL. node especifica o bien una dirección de red numérica (en formato decimal con puntos para IPv4, format hexadecimal para IPv6) o un nombre de host, cuyas direcciones de red son buscadas y resueltas. Si el miembro ai_flags en el parámetro hints contiene la opción AI_NUMERICHOST el parámetro node debe ser una dirección de red numérica. La opción AI_NUMERICHOST suprime cualquier búsqueda larga potencial de direcciones de host.

La función getaddrinfo(3) crea una lista enlazada de estructuras addrinfo , una para cada dirección de red sujeta a cualquier restricción impuesta por el parámetro hints. ai_canonname se modifica para que apunte al nombre oficial del host, si ai_flags en hints incluye la opción AI_CANONNAME. ai_family, ai_socktype, y ai_protocol especifican los parámetros de creación del socket. Se guarda un puntero a la dirección de socket en el miembro ai_addr , y la longitud de la dirección de socket, en bytes, se deja en el miembro ai_addrlen.

Si node es distinto de NULL, la dirección de red en cada estructura socket es inicializada según la opción AI_PASSIVE , que es activada en el miembro ai_flags del parámetro hints. La dirección de red en cada estructura socket se quedará sin definir si la opción AI_PASSIVE está activa. Ésto es usado por aplicaciones servidoras, que intentan aceptar conexiones del cliente en cualquier dirección de red. A la dirección de red se le asignará la dirección de la interfaz de loopback si la opción AI_PASSIVE no está activa. Ésto es usado por aplicaciones cliente, que intentan conectar con servidores que se ejecutan en el mismo host.

service establece el número de puerto en la dirección de red de cada estructura socket. Si service es NULL el número de puerto se dejará sin inicializar.

La función freeaddrinfo(3) libera la memoria que fue asignada a la lista dinámica enlazada res.

VALOR DEVUELTO

getaddrinfo(3) devuelve 0 si tiene éxito, o uno de los siguientes códigos de error:

La familia de direcciones solicitada no está soportada en absoluto.
El tipo de socket solicitado no está soportado en absoluto.
ai_flags contiene opciones no válidas.
El nodo node o el servicio service no son conocidos. Este error también se devuelve si tanto node como service son NULL.
El servicio solicitado no está disponible para el tipo de socket solicitado. Puede estar disponible a través de otro tipo de socket.
El host especificado no tiene ninguna dirección de red en la familia de direcciones especificada.
El host especificado existe, pero no tiene ninguna dirección de red definida.
Memoria insuficiente.
El servidor de nombres devolvió una indicación de fallo permanente.
El servidor de nombres devolvió una indicación de fallo temporal. Pruebe más tarde.
Otro error de sistema, compruebe errno para más detalles.

La función gai_strerror(3) transforma estos códigos de erro en una cadena comprensible, adecuada para el informe de errores.

VÉASE TAMBIÉN

getipnodebyname(3), getipnodebyaddr(3)

18 diciembre 2000 Linux Man Page